<% (display-partial "doctype") %>
<head>
	<% (display-partial "header") %>
</head>

<body>

<div id="wrap">
	<div id="header">
		<% (display-partial "navigation") %>	
		<div class="clear"></div>
	</div>

	<div id="content">
				
		<div class="title nomargin">
			<p><% (title "| Dragonfly web framework") %><p>
		</div>
		
		<h1>Handling Errors</h1>
		<p>
			What happens when a user visits the following link?
		</p>
		<p>
			<a href="<%=(web-root "bar")%>"><%=(string "http://" HTTP_HOST (web-root "bar"))%></a>
		</p>
		<p>
			Go ahead and click it. I can wait.
		</p>
		<p>Back already?</p>
		<p>
			That was an error 404 page, the page that's displayed when all routes failed to match.
		</p>
		<h3>Generating Errors</h3>
		<p>
			Dragonfly uses the <span class="code">DF:display-error</span> function to show these pages. You can too! Here's a quick example of how to use it:
		</p>
		<pre class="textmate-source"><span class="source source_newlisp"><span class="entity entity_paren entity_paren_lisp">(</span><span class="entity entity_name entity_name_function entity_name_function_lisp">display-error</span> <span class="constant constant_numeric constant_numeric_lisp">500</span><span class="entity entity_paren entity_paren_lisp">)</span></span></pre>
		<p>
			Pretty simple huh?
		</p>
		<h3>The <span class="code" style="font-size:inherit">ERROR_TEMPLATE</span></h3>
		<p>
			By default Dragonfly does not show that fancy page you just saw, instead it stores a default (and boring) error template in the symbol <span class="code">DF:ERROR_TEMPLATE</span>. It will use that to display all errors unless it can find an alternative.
		</p>
		<p>For example, if this page didn't exist and no alternative 404 page was found, here's what you'd see:
		</p>
		<div id="demo-error">
			<%
				(Response:status 404)
				(eval-template ERROR_TEMPLATE)
			    (Response:status 200)
			%>
		</div>
		<p>
			How do you specify an alternative?
		</p>
		<h3>Custom Error Templates</h3>
		<p>
			Dragonfly will check inside <span class="code">VIEW_PATHS</span> to see if a view with the error number exists. In other words, a call to <span class="code">(display-error 500)</span> results in a check for:
		</p>
		<pre class="textmate-source"><span class="source source_newlisp"><span class="entity entity_paren entity_paren_lisp">(</span><span class="entity entity_name entity_name_function entity_name_function_lisp">file?</span> <span class="entity entity_paren entity_paren_lisp">(</span><span class="entity entity_name entity_name_function entity_name_function_lisp">Dragonfly:view-path</span> <span class="string string_quoted string_quoted_double string_quoted_double_lisp"><span class="punctuation punctuation_definition punctuation_definition_string punctuation_definition_string_begin punctuation_definition_string_begin_lisp">"</span>500<span class="punctuation punctuation_definition punctuation_definition_string punctuation_definition_string_end punctuation_definition_string_end_lisp">"</span></span><span class="entity entity_paren entity_paren_lisp">))</span></span></pre>
		<p>
			If it exists, it will be displayed instead of <span class="code">ERROR_TEMPLATE</span>.
		</p>
		<p>To see this site's 500 page, click <a href="<%=(web-root "wings/3")%>">here</a>.</p>
		
		<h3>Checking the <span class="code" style="font-size:inherit">dragonfly.log</span></h3>
		
		<p>
			Dragonfly defines an error handler <span class="code">DF:error-handler</span>, that's called whenever an error is generated (for example, by a call to <span class="code">throw-error</span>). You can specify your own handler with a <%(link_to "plugin" "dragonfly_plugins")%>.
		</p>
		<p>
			The default handler makes use of Dragonfly's logging functions to log the stack-trace to the file specified by <span class="code">LOG_FILE_PATH</span> in <b>config.lsp</b>, and then it will call <span class="code">(display-error 500)</span>.
		</p>
		<p>
			If you don't want to publicly show the stack trace in your error 500 template, you don't have to. Just remember to check the log for it. You'll probably also want to setup a <a href="http://en.wikipedia.org/wiki/Cron">cron</a> script roll over the log every now and then to prevent it from getting too large.
		</p>
		<p>
			Dragonfly's logging facilities are defined <b>dragonfly-framework/lib/log.lsp</b>, check <%(link_to "the api" "dragonfly_api")%> for more info.
		</p>
		
		<% (display-partial "continue") %>
		
		<div class="line-dotted"></div>

		<% (benchmark-result) %>
		
		<div class="line-dotted"></div>
		
		
	</div><!-- END CONTENT -->
	
</div><!-- END WRAP -->
<% (display-partial "footer") %>

